Imports System.IO
Imports System.Runtime.CompilerServices
Imports Phoenix.Preferences.Events


Public Interface IPreferencesNode

    ''' <summary>
    ''' Sets  a value for the specified key. 
    ''' </summary>
    ''' <param name="Key">The key whose value to set.</param>
    ''' <value>The value associated with the specified key </value>
    <IndexerName("Value")> Default WriteOnly Property Item(ByVal Key As String) As Object

    ''' <summary>
    ''' Returns the absolute path of a node.
    ''' </summary>
    ''' <value>The absolute path of a node.</value>
    ReadOnly Property AbsolutePath() As String


    ''' <summary>
    ''' Returns the names of this node's subnodes as an array of Strings. 
    ''' Note that this is *different* from Keys, which returns all 
    ''' the names of the values under a node.    
    ''' </summary>
    ReadOnly Property ChildrenNames() As String()

    ''' <summary>
    ''' Returns an array of UserPreferencesNodes that contains all the 
    ''' subnodes of this node.
    ''' </summary>
    ReadOnly Property Children() As IPreferencesNode()

    ''' <summary>
    ''' Returns an array of Strings that contains all the names of the values
    ''' under this node.
    ''' </summary>
    ReadOnly Property Keys() As String()

    ''' <summary>
    ''' Returns the name of this node.
    ''' </summary>
    ReadOnly Property Name() As String

    ''' <summary>
    ''' The parent node of this node. The root 
    ''' node's Parent is always null.
    ''' </summary>
    ReadOnly Property Parent() As IPreferencesNode

    ''' <summary>
    ''' The root node.
    ''' </summary>
    ReadOnly Property Root() As IPreferencesNode

    ''' <summary>
    ''' Returns true if this node is shared by all users. If
    ''' it is a user-specific node, it returns false. For some
    ''' backing store such as isolated storage, which is always 
    ''' isolated by user, this always return false.
    ''' </summary>
    ReadOnly Property IsSystemNode() As Boolean

    '' The silent variant. Whatever happens, returns default.
    Function GetString(ByVal key As String, ByVal DefaultValue As String) As String
    Function GetBoolean(ByVal key As String, ByVal DefaultValue As Boolean) As Boolean
    Function GetByteArray(ByVal key As String, ByVal DefaultValue As Byte()) As Byte()
    Function GetDouble(ByVal key As String, ByVal DefaultValue As Double) As Double
    Function GetSingle(ByVal key As String, ByVal DefaultValue As Single) As Single
    Function GetInt32(ByVal key As String, ByVal DefaultValue As Int32) As Int32
    Function GetInt64(ByVal key As String, ByVal DefaultValue As Int64) As Int64
    Function GetDecimal(ByVal key As String, ByVal DefaultValue As Decimal) As Decimal
    Function GetSerializedObject(ByVal key As String, ByVal objectType As Type, ByVal DefaultValue As Object) As Object

    ''' <summary>
    ''' This method removes all preferences that a node has.
    ''' </summary>
    Sub RemoveAllPreferences()

    ''' <summary>
    ''' Flush the changes to the backing store.
    ''' </summary>
    Sub SynchronizeWithStore()

    ''' <summary>
    ''' Once you get the root node, you'll need to traverse the tree.
    ''' This method accepts both absolute and relative path, and return
    ''' a node that corresponds to that accordingly.
    ''' </summary>
    ''' <param name="pathName"></param>
    ''' <returns></returns>
    Function GetNodeForPath(ByVal pathName As String) As IPreferencesNode

    ''' <summary>
    ''' Returns true if there is already a node that corresponds to the
    ''' given path in this tree.
    ''' </summary>
    ''' <param name="pathName"></param>
    ''' <returns></returns>
    Function NodeExists(ByVal pathName As String) As Boolean

    ''' <summary>
    ''' Removes a node on which this method is called on, plus all its
    ''' children, recursively.
    ''' </summary>
    Sub RemoveNode()

    ''' <summary>
    ''' Removes a specific preference that is associated with the
    ''' specified key. If the key doesn't exist, returns false.
    ''' </summary>
    ''' <param name="key"></param>
    ''' <returns></returns>
    Function RemovePreference(ByVal key As String) As Boolean

    '' events
    '' in case a child of the node has been 
    '' removed or added
    Event ChildNodeAdded As ChildNodeEventHandler
    Event ChildNodeRemoved As ChildNodeEventHandler

    '' in case a preference has been added,
    '' removed, or its value changed.
    Event PreferenceChanged As PreferenceChangeEventHandler

End Interface

